The VhsClient object contains the following methods:
Note: A description for each CxVhsLib helper object can be found in VhsClient Helper Objects.
The AddHistoryPoint method adds a new history point to a VHS.
AddHistoryPoint(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: AddHistoryPointReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: AddHistoryPointResp |
Returns 0 if successful and a non-zero value if an error occurred. Adding a tag that has already been added will not generate an error. Adding a new point to the VHS in this way does not result in the corresponding CVS actually recording new values to the VHS for the point. History must be enabled in the PNT for the CVS to process new values and log them to the VHS. This method is not generally used.
Example
The following example adds a new point to CYGDEMO.UIS and alerts the user of any errors.
|
Sub VhsAddHistoryPoint() Dim VhsClient,req, resp, tag Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.AddHistoryPointReq") Set resp = CreateObject("CxVhsLib.AddHistoryPointResp") Set tag = CreateObject("CxVhsLib.HistoryTagString") VhsClient.Connect("CYGDEMO.VHS")
'The point to be created tag.TagString = "CYGDEMO.UIS.00001235" req.TagString = tag
VhsClient.AddHistoryPoint req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed successfully" End If End Sub |
The Connect method connects the object to a service.
Connect(DomainSiteService As String)
| Parameter | Required | Description |
|---|---|---|
|
DomainSiteService |
Yes |
The [Domain]Site.Service to which to connect. A domain is optional. The service must be a valid VHS. |
Returns 0 if successful and a non-zero value if the connection failed.
Example
The following example connects the VhsClient object to the CYGDEMO.VHS on domain 5410:
|
Sub VhsConnect() 'Connect to a VHS Dim VhsClient Set VhsClient = CreateObject("CxVhsLib.VhsClient") VhsClient.Connect("[5410]CYGDEMO.VHS") End Sub |
The ContinueHistoryRead method is used after StartHistoryRead for successive calls until all history entries have been returned.
ContinueHistoryRead(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: ContinueHistoryReadReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: HistoryReadResp |
When the Response object’s Error variable is equal to 10, the end of the history values has been reached.
Example
The following example reads two more values from the history. It uses a global variable, g_Restart, that was set in a StartHistoryRead method.
|
Sub VhsContinueHistoryRead() Dim VhsClient, req, resp Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.ContinueHistoryReadReq") Set resp = CreateObject("CxVhsLib.HistoryReadResp") VhsClient.Connect("CYGDEMO.VHS")
req.Count = 2 req.Restart = g_Restart
VhsClient.ContinueHistoryRead req, resp
g_Restart = resp.Restart
If resp.Error = 10 Then edtMessageBox.Text = "End of history has been reached" Elseif resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed successfully" For i = 0 To resp.Count - 1 ListBox2.AddString(i & " - " & _ resp.entry(i).Status & " - " & _ resp.entry(i).TimeStamp & " - " & _ resp.entry(i).Value) Next End If End Sub |
The ContinueHistoryReadEx method is used after StartHistoryReadEx for successive calls until all history entries have been returned.
ContinueHistoryReadEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: ContinueHistoryReadExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: HistoryReadExResp |
When the Response object’s Error variable is equal to 10, the end of the history values has been reached.
Example
The following example reads two more values from the history. It uses a global variable, g_Restart, that was set in a StartHistoryReadEx method.
|
Sub VhsContinueHistoryReadEx() Dim VhsClient, req, resp Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.ContinueHistoryReadExReq") Set resp = CreateObject("CxVhsLib.HistoryReadExResp") VhsClient.Connect("CYGDEMO.VHS")
req.Count = 3 req.Restart = g_Restart
VhsClient.ContinueHistoryReadEx req, resp
g_Restart = resp.Restart
If resp.Error = 10 Then edtMessageBox.Text = "End of history" Elseif resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed successfully" For i = 0 To resp.Count - 1 ListBox2.AddString(i & " - " & _ resp.entry(i).Status & " - " & _ resp.entry(i).UserStatus & " - " & _ resp.entry(i).TimeStamp & " - " & _ resp.entry(i).Value) Next End If End Sub |
The DeleteHistoryPoint method deletes a point from the VHS.
DeleteHistoryPoint(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: DeleteHistoryPointReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: DeleteHistoryPointResp |
Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example deletes CYGDEMO.UIS.00001235 from the VHS.
|
Sub VhsDeleteHistoryPoint() Dim VhsClient, req, resp, tag Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.DeleteHistoryPointReq") Set resp = CreateObject("CxVhsLib.DeleteHistoryPointResp") Set tag = CreateObject("CxVhsLib.HistoryTagString") VhsClient.Connect("CYGDEMO.VHS")
'The point to be deleted tag.TagString = "CYGDEMO.UIS.00001235" req.TagString = tag
VhsClient.DeleteHistoryPoint req, resp
'Error handling If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed successfully" End If End Sub |
The DeleteHistoryValueEx method deletes a history value from a point in the VHS.
DeleteHistoryValueEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: DeleteHistoryValueExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: DeleteHistoryValueExResp |
Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example deletes a history value obtained from ListHistoryValuesEx (g_ValueEntryEx). It is also possible to manually input the history value.
|
Sub VhsDeleteHistoryValueEx() Dim VhsClient, req, resp, tag Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.DeleteHistoryValueExReq") Set resp = CreateObject("CxVhsLib.DeleteHistoryValueExResp") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsClient.Connect("CYGDEMO.VHS")
tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" req.TagStringEx = tag req.ValueEntryEx = g_ValueEntryEx req.Operations = 1
VhsClient.DeleteHistoryValueEx req, resp
'Error handling If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed successfully" End If End Sub |
The Disconnect method disconnects from the service.
Disconnect() As Integer
Returns 0 if successful and a non-zero value if the disconnect failed.
Example
The following example disconnects the client from the VHS.
|
Sub Disconnect() VhsClient.Disconnect End Sub |
The EditHistoryPoint method stores history entries for multiple points.
EditHistoryPoint(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: EditHistoryPointReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: EditHistoryPointResp |
This method is obsolete. It has been replaced by StoreHistoryList.
The GetConsoleData method returns the console text and display attributes as two 25x80 arrays of unsigned characters.
GetConsoleData(ByRef pText, ByRef pAttr) As Integer
| Parameter | Required | Description |
|---|---|---|
|
pText |
Yes |
A two-dimensional 25x80 array of console text attributes returned by this method. |
|
pAttr |
Yes |
A two-dimensional 25x80 array of console display attributes returned by this method. |
This method returns 0 if successful.
Example
The following example writes the console text and display attributes to a CSV file.
|
Sub Dim aryText, aryAttr, nRet nRet = VhsClient.GetConsoleData(aryText, aryAttr)
' Write text attributes to CSV file Dim i, j, strMsg For i = 0 To UBound(aryText, 1) For j = 0 To UBound(aryText, 2) strMsg = strMsg + CStr(aryText(i, j)) + "," Next strMsg = strMsg + vbCr Next
dim fso, file Set fso = CreateObject("Scripting.FileSystemObject") Set file = fso.OpenTextFile("c:\console_text_attrs.csv", 2, True) file.WriteLine(strMsg) file.Close
strMsg = ""
' Write display attributes to CSV file For i = 0 To UBound(aryAttr, 1) For j = 0 To UBound(aryAttr, 2) strMsg = strMsg + CStr(aryAttr(i, j)) + "," Next strMsg = strMsg + vbCr Next
Set file = fso.OpenTextFile("c:\console_disp_attrs.csv", 2, True) file.WriteLine(strMsg) file.Close
MsgBox nRet End Sub |
The GetMissingDataTimesForPoints method gets dates in an interval that don’t have the specified number of value updates.
GetMissingDataTimesForPoints(Points As Variant, Period As Integer, Units As String, MinRequired As Integer, StartTime As Variant, EndTime As String, MissingDataTimes As String, ErrorTextOut as String) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
Points |
Yes |
Array of points to check for missing data. |
|
Period |
Yes |
The interval in which you expect values to exist. |
|
Units |
Yes |
The interval of the unit. This can be "Seconds," "Minute," "Hours," or "Days." |
|
MinRequired |
Yes |
Minimum number of values expected to be within the interval. If there is less than this number, the interval will be returned in MissingDataTimes. |
|
StartTime |
Yes |
The interval time you want to start searching for missing values. |
|
EndTime |
Yes |
The interval time you want to stop searching for values. |
|
MissingDataTimes |
Yes |
Output, two-dimensional array. The first column of the array is the point tag. The second column is an array where index 0 is the name of the point, and index 1 is an array of timestamps that represent intervals that don’t meet the minimum number of required values. |
|
ErrorTextOut |
Yes |
Output. An error message, if applicable. |
Example
The following example gets all the days in February 2010 that CYGDEMO.UIS.00000068 and CYGDEMO.UIS.00000069 were not updated at least once.
|
Sub VhsGetMissingDataTimesForPoints Dim objVhs, tags, arrPoints, arrTimes, strError, i Set objVhs = CreateObject("CxVhsLib.VhsClient.1") objVhs.Connect("CYGDEMO.VHS")
tags = Array("CYGDEMO.UIS.00000068", "CYGDEMO.UIS.00000069")
'Get all days from February 1, 2010 until the current date 'That haven't been updated at least once objVhs.GetMissingDataTimesForPoints tags, 1, "Days", 1, _ CDate("02/01/2010"), Now, arrPoints, strError
If strError <> "" Then MsgBox strError Else 'Set arrTimes to all the timestamps for the first point arrTimes = arrPoints(0,1) 'Prints the point name and all its timestamps For i = 0 To UBound(arrTimes) listbox2.AddString(arrPoints(0,0) & " - " & CDate(arrTimes(i))) Next
'Set arrTimes to all the timestamps for the second point arrTimes = arrPoints(1,1) 'Prints the point name and all its timestamps For i = 0 To UBound(arrTimes) listbox2.AddString(arrPoints(1,0) & " - " & CDate(arrTimes(i))) Next End If End Sub |
The GetNamedArrayValues method reads the history entries from multiple points that were in effect for the given date.
GetNamedArrayValues(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: GetNamedArrayValuesReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: GetNamedArrayValuesResp |
If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.
Note: GetNamedArrayValuesExReq objects are limited to 63 total objects within the array. Objects greater than 63 will cause an exception.
Example
The following example displays the history entry data for two points in a list box.
|
Sub VhsGetNamedArrayValues() Dim VhsClient, req, resp, tag0, tag1 Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.GetNamedArrayValuesReq") Set resp = CreateObject("CxVhsLib.GetNamedArrayValuesResp") Set tag0 = CreateObject("CxVhsLib.HistoryTagString") Set tag1 = CreateObject("CxVhsLib.HistoryTagString") VhsClient.Connect("CYGDEMO.VHS")
req.count = 2 tag0.TagString = "CYGDEMO.UIS.00000068" req.TagString(0) = tag0 req.TimeStamp(0) = CDate("1/1/2010 15:48:00")
tag1.TagString = "CYGDEMO.UIS.00000069" req.TagString(1) = tag1 req.TimeStamp(1) = CDate("1/1/2010 15:48:00")
VhsClient.GetNamedArrayValues req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else ListBox2.ResetContent Dim i For i = 0 To resp.count - 1 ListBox2.AddString("Status - " & resp.entry(i).Status & _ "; TimeStamp - " & resp.entry(i).Timestamp & _ "; Value - " & resp.entry(i).Value) Next End If End Sub |
The GetNamedArrayValuesEx method reads the history entries from multiple history points that were in effect for the given date.
GetNamedArrayValuesEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: GetNamedArrayValuesExReq |
|
Response |
Yes |
The response object that contains the output of this method. |
If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.
Example
The following example displays the history entry data for two points in a list box.
|
Sub VhsGetNamedArrayValuesEx() Dim VhsClient, req, resp, tag0, tag1 Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.GetNamedArrayValuesExReq") Set resp = CreateObject("CxVhsLib.GetNamedArrayValuesExResp") Set tag0 = CreateObject("CxVhsLib.HistoryTagStringEx") Set tag1 = CreateObject("CxVhsLib.HistoryTagStringEx") VhsClient.Connect("CYGDEMO.VHS")
req.count = 2 tag0.TagString = "CYGDEMO.UIS.00000068" req.TagString(0) = tag0 req.TimeStamp(0) = CDate("1/1/2010 15:48:00")
tag1.TagString = "CYGDEMO.UIS.00000069" req.TagString(1) = tag1 req.TimeStamp(1) = CDate("1/1/2010 15:48:00")
VhsClient.GetNamedArrayValuesEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.text = resp.count ListBox2.ResetContent Dim i For i = 0 To resp.Count - 1 ListBox2.AddString("Status - " & resp.entry(i).Status & _ "; Userstatus - " & resp.entry(i).UserStatus & _ "; TimeStamp - " & resp.entry(i).Timestamp & _ "; Value - " & resp.entry(i).Value) Next End If End Sub |
The GetPointStats method gets statistics for a given history point.
GetPointStats(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: GetPointStatsReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: GetPointStatsResp |
Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example gets statistics for CYGDEMO.UIS.00000068 and displays them in a list box.
|
Sub VhsGetPointStats() Dim VhsClient, req, resp, tag Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.GetPointStatsreq") Set resp = CreateObject("CxVhsLib.GetPointStatsresp") Set tag = CreateObject("CxVhsLib.HistoryTagString") bjVhs.Connect("CYGDEMO.VHS")
tag.TagString = "CYGDEMO.UIS.00000068" req.TagString = tag
VhsClient.GetPointStats req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else ListBox2.ResetContent ListBox2.AddString("Expiration Date: " & resp.ExpirationDays) ListBox2.AddString("First History Entry: " & resp.TimeStampStart) ListBox2.AddString("Last History Entry: " & resp.TimeStampEnd) ListBox2.AddString("Total History Entries: " & resp.Entrycount) End If End Sub |
The GetPointStatsEx method gets statistics for an array of history points.
GetPointStatsEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: GetPointStatsExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: GetPointStatsExResp |
Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example gets statistics for CYGDEMO.UIS.00000068 and CYGDEMO.UIS.00000069 and displays them in a list box.
|
Sub VhsGetPointStatsEx() Dim VhsClient, req, resp, bRc, tag1, tag2 Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.GetPointStatsExReq") Set resp = CreateObject("CxVhsLib.GetPointStatsExResp") Set tag0 = CreateObject("CxVhsLib.HistoryTagStringEx") Set tag1 = CreateObject("CxVhsLib.HistoryTagStringEx") bRc = VhsClient.Connect("CYGDEMO.VHS")
req.Count = 2 tag0.TagString = "CYGDEMO.UIS.00000069:CYG_METER_PSTATIC" tag1.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" req.TagString(0) = tag0 req.TagString(1) = tag1
VhsClient.GetPointStatsEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else ListBox2.ResetContent Dim i For i = 0 To resp.Count - 1 ListBox2.AddString("Point Number: " & i) ListBox2.AddString("Point Error: " & resp.PointError(i)) ListBox2.AddString("Total History Entries: " & _ resp.Statistics(i).EntryCount) ListBox2.AddString("First History Entry: " & _ resp.Statistics(i).TimeStampStart) ListBox2.AddString("Last History Entry: " & resp.Statistics(i).TimeStampEnd) ListBox2.AddString("Expiration Date: " & resp.Statistics(i).ExpirationDays) ListBox2.AddString("") Next End If End Sub |
The GetReferences method refreshes the list of services referenced by the connected service.
GetReferences() As Integer
Example
The following example refreshes the referenced services.
|
Sub VhsGetReferences() Dim VhsClient Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") VhsClient.Connect("CYGDEMO.VHS")
VhsClient.GetReferences() End Sub |
The InsertHistoryList method stores multiple history values for multiple points.
InsertHistoryList(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: InsertHistoryListReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: InsertHistoryListResp |
This method has been made obsolete by StoreHistoryList and no longer works.
The ListHistoryPointsEx method lists history points in alphabetic order from the given start index. The ListHistoryPointsEx method has a upper bound array count of 53; the method can only retrieve a maximum of 53 response items per request. The only way to get all points is to iterate through using the last returned item as the new starting point. See the second example below.
ListHistoryPointsEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: ListHistoryPointsExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: ListHistoryPointsExResp |
Returns 0 if successful and a non-zero value if an error occurred.
Examples
The following example gets a list of all history points whose Point ID is greater than 00000123.
|
Sub VhsListHistoryPointsEx() Dim VhsClient, req, resp Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.ListHistoryPointsExReq") Set resp = CreateObject("CxVhsLib.ListHistoryPointsExResp") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsClient.Connect("CYGDEMO.VHS")
tag.TagString = "CYGDEMO.UIS.00000123:FREEZIE_METER_VET" req.TagString = tag VhsClient.ListHistoryPointsEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else ListBox2.ResetContent Dim i For i = 0 To resp.Count - 1 ListBox2.AddString( i & " - " & _ resp.Statistics(i).ExpirationDays & " - " & _ resp.Statistics(i).TimeStampStart & " - " & _ resp.Statistics(i).TimeStampEnd & " - " & _ resp.Statistics(i).Entrycount & " - " & _ resp.TagString(i).TagString) Next End IF End Sub |
The following example iterates through the returned values for ListHistoryPointsEx:
|
' VHS Client Request and Response objects.
Dim objVHSClient : Set objVHSClient = CreateObject("CxVHS.VhsClient") Dim objVHSRequest : Set objVHSRequest = CreateObject("CxVhsLib.ListHistoryPointsExReq") Dim objVHSResponse : Set objVHSResponse = CreateObject("CxVhsLib.ListHistoryPointsExResp") Dim objVHSTag : Set objVHSTag = CreateObject("CxVhsLib.HistoryTagStringEx")
' Connect the Client to the Service. Call objVHSClient.Connect("CYGDEMO.VHS")
' Prepare the Request objVHSTag.TagString = "CYGDEMO.UIS.00000000" ' Let's start at "Zero" to try and get everything. objVHSRequest.TagString = objVHSTag
' Send the Initial Request Call objVHSClient.ListHistoryPointsEx(objVHSRequest, objVHSResponse) Dim blnFlag : blnFlag = True
' Iterate through the response object Dim intX : intX = 0 Dim intY : intY = 0 ' The UB of the return array ReDim aryVHSPoints(intX)
Dim objFSO : Set objFSO = CreateObject("Scripting.FileSystemObject") Dim objFile : Set objFile = objFSO.CreateTextFile("C:\temp\ListHistoryPointsEx.txt", True, -2)
Dim strHeader : strHeader = "******************** ListHistoryValuesEx Results ********************" Dim strFooter : strFooter = "*********************************************************************"
Dim objPoints : Set objPoints = CreateObject("CxScript.Points") Dim objPoint
Call objFile.Write(strHeader & vbCrLf & vbCrLf)
Dim blnStop : blnStop = True
Do While(intY <= objVHSResponse.TotalPointCount)
For intX = 0 To (objVHSResponse.Count -1) ReDim Preserve aryVHSPoints(intY) aryVHSPoints(intY) = objVHSResponse.TagString(intX).TagString intY = intY + 1
Next
' Continue the loop till the end... On Error Resume next Set objPoint = objPoints.Point(aryVHSPoints(intY -1)) objVHSTag.TagString = objPoint.Tag objVHSRequest.TagString = objVHSTag Call objVHSClient.ListHistoryPointsEx(objVHSRequest, objVHSResponse)
Loop
ReDim Preserve aryVHSPoints(intY -1) intY = 0
For Each thing In aryVHSPoints Call objFile.Write(intY+1 & " | " & thing & vbCrLf) intY = intY + 1
Next
Call objFile.Write(strFooter) |
The ListHistoryValuesEx method reads the history values from a point in chronological order based on the given timestamp. The ListHistoryValuesEx has a upper bound array count of 111; the method can only retrieve a maximum of 111 response items per request. The only way to get all values is to iterate through using the last returned item as the new starting point. See the second example below.
ListHistoryValuesEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: ListHistoryValuesExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: ListHistoryValuesExResp |
Returns 0 if successful, or return codes: NO_HISTORY_FOR_TIME (12) indicating that there is no history for the time requested or END_OF_HISTORY (10) indicating that there is no more history to retrieve.
Note: We recommend avoiding these message wrappers in favor of the more user-friendly iterators, PointIterator, ValueIterator, and ValueIteratorReverse.
Example
The following example gets all the history values for a point after January 1, 2009 and displays them in a list box. It also stores the first history value in a global variable so it can be used by other methods.
|
Sub VhsListHistoryValuesEx() Dim VhsClient, req, resp, tag Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.ListHistoryValuesExReq") Set resp = CreateObject("CxVhsLib.ListHistoryValuesExResp") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsClient.Connect("CYGDEMO.VHS")
tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" Req.TagString = tag Req.TimeStampStart = CDate("1/1/2009")
VhsClient.ListHistoryValuesEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else Dim i ListBox2.ResetContent For i = 0 To resp.Count - 1 ListBox2.AddString(resp.valueEntry(i).Status & " - " & _ resp.valueEntry(i).UserStatus & " - " & _ resp.valueEntry(i).TimeStamp & " - " & _ resp.valueEntry(i).Value) Next
'Sets a global variable to the first value entry 'so it can be used by other methods Set g_ValueEntryEx = resp.valueEntry(0) End If End Sub |
The following example iterates through the returned values for ListHistoryValuesEx:
|
Sub VhsListHistoryValuesEx(Byval Cur_Tag, Byval Vhs_Site)
Dim request : Set request = CreateObject("CxVhsLib.ListHistoryValuesExReq") Dim response : Set response = CreateObject("CxVhsLib.ListHistoryValuesExResp") Dim strHistTag : Set strHistTag = CreateObject("CxVhsLib.HistoryTagStringEx")
Dim strHistoryEntries : strHistoryEntries = "" Dim intUnreliable : intUnreliable = 0
VhsClient.Connect(strVHSSite)
strHistTag.TagString = strTag request.TagString = strHistTag request.TimeStampStart = CDate("1/1/1985")
Dim loop_until loop_until = True
Dim X : X = 0
Dim Z : Z = 0
While(loop_until)
Z = 0
VhsClient.ListHistoryValuesEx request, response
Dim i : i = 0 Dim j : j = 0
Dim timeEntry Dim valueEntry Dim statusEntry Dim historyEntry Dim checkEntry
Dim checker Dim Rchecker Dim results
If(response.Error <> 0 And response.Error <> 10)Then
' if the response error is 0, there is no error ' if the response error is 10, this means "END_OF_HISTORY" -- we're done
Else
For i = 0 To response.Count - 1
' What can you do with the results?
'objDictionary_Time.SetKeyValue X,response.ValueEntry(i).Value 'objDictionary_Value.SetKeyValue X,response.ValueEntry(i).Timestamp 'objDictionary_Status.SetKeyValue X,response.ValueEntry(i).Status
'timeEntry = objDictionary_Time.FindValue(X) 'valueEntry = objDictionary_Value.FindValue(X) 'statusEntry = objDictionary_Status.FindValue(X)
X = X + 1 Z = Z + 1
Next
End If
If(response.Count = 111)Then
' Let's start at the last timepoint retrieved and move forward. request.TimeStampStart = CDate(response.ValueEntry(Z-1).Timestamp)
Else ' Exit loop_until = False
End if
Wend
End Sub |
The StartHistoryRead method reads the history entries within an inclusive GMT date range.
StartHistoryRead(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: StartHistoryReadReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: StartHistoryReadResp |
Returns 0 if successful and a non-zero value if an error occurred. If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.
Example
The following example reads two history entries between January 1, 2009 and the current date. It then stores Restart in a global variable so that ContinueHistoryRead can read the next set of entries.
|
Sub VhsStartHistoryRead() Dim VhsClient, req, resp, tag Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.StartHistoryReadReq") Set resp = CreateObject("CxVhsLib.HistoryReadResp") Set tag = CreateObject("CxVhsLib.HistoryTagString") VhsClient.Connect("CYGDEMO.VHS")
tag.TagString = "CYGDEMO.UIS.00000068" req.TagString = tag req.Count = 2 req.TimeStampStart = CDate("01/01/2009")
VhsClient.StartHistoryRead req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else g_restart = resp.Restart
ListBox2.ResetContent For i = 0 To resp.Count - 1 ListBox2.AddString(i & " - " & _ resp.entry(i).Status & " - " & _ resp.entry(i).TimeStamp & " - " & _ resp.entry(i).Value) Next End If End Sub |
The StartHistoryReadEx method reads the history entries within an inclusive GMT date range.
StartHistoryReadEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: StartHistoryReadExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: HistoryReadExResp |
This method is capable of returning rollups for the given period. By default, raw values are returned. Returns 0 if successful and a non-zero value if an error occurred. If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.
Example
The following example reads the last value entry from each 30 day period. It then stores Restart in a global variable so that ContinueHistoryReadEx can read the next three entries.
|
Sub VhsStartHistoryReadEx() Dim VhsClient, req, resp, tag Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.StartHistoryReadExReq") Set resp = CreateObject("CxVhsLib.HistoryReadExResp") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsClient.Connect("CYGDEMO.VHS")
tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" req.TagString = tag req.TimeStampStart = "12/3/2018" req.TimeStampEnd = Now req.RollupType = 9 'Gets the last value entry... req.RollupPeriod = 30 '...from each thirty... req.RollupUnits = 3 '...day period req.Count = 3
VhsClient.StartHistoryReadEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else g_restart = resp.Restart
ListBox2.ResetContent For i = 0 To resp.Count - 1 ListBox2.AddString(resp.Entry(i).Status & " - " & _ resp.entry(i).UserStatus & " - " & _ resp.entry(i).TimeStamp & " - " & _ resp.entry(i).Value) Next End If End Sub |
The StoreHistoryList method stores history entries for multiple history points.
StoreHistoryList(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: StoreHistoryListReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: StoreHistoryListResp |
The entries do not have to be in chronological order because they will be correctly inserted or appended, however performance is better if they are. Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example stores new value entries for two history points.
|
Sub VhsStoreHistoryList() Dim VhsClient, req, resp, entry0, entry1, tag0, tag1 Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.StoreHistoryListReq") Set resp = CreateObject("CxVhsLib.StoreHistoryListResp") Set entry0 = CreateObject("CxVhsLib.HistoryEntry") Set entry1 = CreateObject("CxVhsLib.HistoryEntry") Set tag0 = CreateObject("CxVhsLib.HistoryTagString") Set tag1 = CreateObject("CxVhsLib.HistoryTagString") VhsClient.Connect("CYGDEMO.VHS")
Req.Count = 2
tag0.TagString = "CYGDEMO.UIS.00000068" req.TagString(0) = tag0 entry0.Status = 7 entry0.TimeStamp = Now entry0.Value = 999 req.Entry(0) = entry0
tag1.TagString = "CYGDEMO.UIS.00000069" req.TagString(1) = tag1 entry1.Status = 7 entry1.TimeStamp = Now entry1.Value = 123 Req.Entry(1) = entry1
VhsClient.StoreHistoryList req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed Successfully" End If End Sub |
The StorePointHistory method stores multiple history entries for a single point.
StorePointHistory(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method Type: StorePointHistoryReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: StorePointHistoryResp |
The entries do not have to be in chronological order because they will be correctly inserted or appended, however performance is better if they are. Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example stores two history entries for a point. The first entry is inserted at the appropriate time, while the second entry is appended to the history list to be the latest value.
|
Sub VhsStorePointHistory() Dim VhsClient, req, resp, entry0, entry1, tag Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.StorePointHistoryReq") Set resp = CreateObject("CxVhsLib.StorePointHistoryResp") Set entry0 = CreateObject("CxVhsLib.HistoryEntry") Set entry1 = CreateObject("CxVhsLib.HistoryEntry") Set tag = CreateObject("CxVhsLib.HistoryTagString") VhsClient.Connect("CYGDEMO.VHS")
Req.Count = 2
tag.TagString = "CYGDEMO.UIS.00000068" req.TagString = tag
entry0.Status = 7 entry0.TimeStamp = CDate((01/02/2010") entry0.Value = 123 req.Entry(0) = entry0
entry1.Status = 7 entry1.TimeStamp = Now entry1.Value = 456 req.Entry(1) = entry1
VhsClient.StorePointHistory req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed Successfully" End If End Sub |
The StorePointHistory method stores multiple history entries for a single point.
StorePointHistory(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: StorePointHistoryExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: StorePointHistoryExResp |
The entries do not have to be in chronological order because they will be correctly inserted or appended, however performance is better if they are. Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example stores two history entries for a point. The first entry is inserted at the appropriate time, while the second entry is appended to the history list to be the latest value.
|
Sub VhsStorePointHistoryEx() Dim VhsClient, req, resp, entry0, entry1, tag Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.StorePointHistoryExReq") Set resp = CreateObject("CxVhsLib.StorePointHistoryExResp") Set entry0 = CreateObject("CxVhsLib.HistoryEntryEx") Set entry1 = CreateObject("CxVhsLib.HistoryEntryEx") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsClient.Connect("CYGDEMO.VHS")
req.Count = 2
tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" req.TagString = tag
entry0.Status = 7 entry0.UserStatus = 0 entry0.TimeStamp = CDate("01/02/2010") entry0.Value = 111 req.Entry(0) = entry0
entry1.Status = 7 entry1.UserStatus = 0 entry1.TimeStamp = Now entry1.Value = 222 req.Entry(1) = entry1
VhsClient.StorePointHistoryEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed Successfully" End If End Sub |
The UpdateHistoryValuesEx method updates a point’s history value.
UpdateHistoryValueEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for the history value being updated. Type: UpdateHistoryValueExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: UpdateHistoryValueExResp |
Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example adds a new history value to the end of the history list. The value is the current time.
|
Sub VhsUpdateHistoryValueEx() Dim VhsClient, req, resp, history, value, tag Set VhsClient = CreateObject("CxVhsLib.VhsClient.1") Set req = CreateObject("CxVhsLib.UpdateHistoryValueExReq") Set resp = CreateObject("CxVhsLib.UpdateHistoryValueExResp") Set history = CreateObject("CxVhsLib.HistoryEntryEx") Set value = CreateObject("CxVhsLib.ValueEntryEx") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsClient.Connect("CYGDEMO.VHS")
tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" req.TagStringEx = tag
history.TimeStamp = Now history.Value = Time req.ValueEntryNew = history
VhsClient.UpdateHistoryValueEx req, resp
If resp.ErrorType <> 0 Then edtMessageBox.Text = "Error number " & resp.ErrorType Else edtMessageBox.Text = "Completed Successfully" End If End Sub |
|
|
|
